text

type text

An immutable character string data type.

Since

0.6.0

Functions

Link copied to clipboard
pure function char_at(index: integer): integer

Retrieves the 16-bit code of the character at the specified index within this text.

Link copied to clipboard
(alias) pure function charAt(index: integer): integer

Retrieves the 16-bit code of the character at the specified index within this text.

Alias
Link copied to clipboard
pure function compare_to(other: text): integer

Compares this text to another text lexicographically, based on the Unicode value of each character in each text object.

Link copied to clipboard
(alias) pure function compareTo(other: text): integer

Compares this text to another text lexicographically, based on the Unicode value of each character in each text object.

Link copied to clipboard
pure function contains(text: text): boolean

Checks if this text contains the specified substring.

Note that for all texts t, t.contains('') is true, and for all texts u and v such that u == v, u.contains(v) is true.

t.contains(u) is equivalent to t.index_of(u) >= 0.

Link copied to clipboard
pure function empty(): boolean

Returns true if this text is empty, false otherwise.

x.empty() is equivalent to x.size() == 0.

Link copied to clipboard
(alias) pure function encode(): byte_array

Converts this text to an array of UTF-8 encoded bytes.

Alias
Link copied to clipboard
pure function ends_with(suffix: text): boolean

Checks if this text ends with the specified suffix.

Note that for all texts t, t.ends_with('') is true, and for all texts u and v such that u == v, u.ends_with(v) is true.

Link copied to clipboard
(alias) pure function endsWith(suffix: text): boolean

Checks if this text ends with the specified suffix.

Note that for all texts t, t.ends_with('') is true, and for all texts u and v such that u == v, u.ends_with(v) is true.

Alias
Link copied to clipboard
pure function format(args: anything...): text

Uses this text as a format string and returns the text obtained by substituting the specified arguments.

Supports many of the format specifiers found in other programming languages, including:

  • %s for text

  • %d for integers and big_integers in decimal (base 10) representation

  • %o for integers and big_integers in octal (base 8) representation

  • %x for integers and big_integers in hexadecimal (base 16) representation

  • %f for decimal (supports precision, e.g. %.2f for two decimal places)

  • %b for booleans (output in lower-case, i.e. true and false)

  • %B for booleans (output in upper-case, i.e. TRUE and FALSE)

Examples:

  • 'My integer is %d.'.format(123) returns 'My integer is 123.'.

  • 'See you...%10s.'.format('later') returns 'See you... later.'.

  • 'Earnings: daily=%f, weekly=%f, monthly=%f.'.format(312.45, 534.78, 2199.67) returns 'Earnings: daily=312.450000, weekly=534.780000, monthly=2199.670000.'.

  • ''%d %o %x'.format(14, 14, 14)' returns '14 16 e'.

If any format specifier is incompatible with the type of its corresponding argument, or if there are more specifiers requiring substitution than there are arguments, all format specifiers are left unsubstituted in the output text.

All format specifiers are also left unsubstituted in the output text when any argument is null, except when it matches the specifier is %s, in which case the text 'null' is substituted (assuming the other arguments and specifiers are correctly matched).

If there are more arguments than format specifiers, the extra arguments are ignored, but matched arguments are still substituted (assuming they match correctly).

Link copied to clipboard
pure static function from_bytes(bytes: byte_array, [ignore_errors: boolean]): text

Create a text representation of the given bytes.

By default, an exception is thrown if invalid UTF-8 characters are encountered, however if the optional parameter ignore_errors is provided as true, invalid characters are instead replaced with a placeholder.

Link copied to clipboard
pure function index_of(text: text): integer

Search for the first occurrence of the specified substring within this text.

pure function index_of(text: text, start: integer): integer

Returns the position of the first occurrence of the specified substring within this text, starting at the specified index, or -1 if the text is not found.

Link copied to clipboard
(alias) pure function indexOf(text: text): integer

Search for the first occurrence of the specified substring within this text.

Alias
(alias) pure function indexOf(text: text, start: integer): integer

Returns the position of the first occurrence of the specified substring within this text, starting at the specified index, or -1 if the text is not found.

Alias
Link copied to clipboard
pure function last_index_of(text: text): integer

Returns the index within this text of the last occurrence of the specified string, or -1 if not found.

pure function last_index_of(text: text, max: integer): integer

Returns the index within this text of the last occurrence of the specified string, starting from the specified startIndex, or -1 if not found.

Link copied to clipboard
(alias) pure function lastIndexOf(text: text): integer

Returns the index within this text of the last occurrence of the specified string, or -1 if not found.

(alias) pure function lastIndexOf(text: text, max: integer): integer

Returns the index within this text of the last occurrence of the specified string, starting from the specified startIndex, or -1 if not found.

Link copied to clipboard
(alias) pure function len(): integer

Returns the number of characters in this text.

Alias
Link copied to clipboard
pure function like(pattern: text): boolean

Matches this text against the specified SQL LIKE pattern.

Use '_' to match any single character, and '%' to match any sequence of zero or more characters. The escape sequences '\\_', '\\%' and '\\\\' match the literal characters '_', '%' and '\' respectively.

Examples:

val names = ["Alice", "Victor", "Viktor", "Victoria", "V\\ctor"];
print(names @* { .like("Vi_tor") }); // prints [Victor, Viktor]
print(names @* { .like("Vic%") }); // prints [Victor, Victoria]
print(names @* { .like("V\\\\c%") }); // prints [V\ctor]
Link copied to clipboard
pure function lower_case(): text

Returns the text obtained by converting all alphabetic characters in this text to lower case.

Link copied to clipboard
(alias) pure function lowerCase(): text

Returns the text obtained by converting all alphabetic characters in this text to lower case.

Link copied to clipboard
pure function matches(regex: text): boolean

Matches this text against the specified regular expression.

Regular expressions use the same syntax as java.util.regex.Pattern.

Examples:

val names = ["Alice", "Victor", "Viktor", "Victoria", "V\\ctor"];
print(names @* { .matches("Vi[a-z]tor") }); // prints [Victor, Viktor]
print(names @* { .matches("Vic.*") }); // prints [Victor, Victoria]
print(names @* { .matches("V\\\\c.*") }); // prints [V\ctor]
Link copied to clipboard
pure function repeat(n: integer): text

Repeat this text n times. SQL compatible.

Examples:

  • 'abc'.repeat(3) returns 'abcabcabc'

  • ''.repeat(3) returns ''

  • 'abc'.repeat(0) returns ''

Link copied to clipboard
pure function replace(old_value: text, new_value: text): text

Returns the text obtained by replacing all occurrences of the substring old_value in this text with new_value.

Link copied to clipboard
pure function reversed(): text

Returns a reversed copy of this text. SQL compatible.

Examples:

  • ''.reversed() returns ''

  • 'a'.reversed() returns 'a'

  • 'abc'.reversed() returns 'cba'

Link copied to clipboard
pure function size(): integer

Returns the number of characters in this text.

Link copied to clipboard
pure function split(delimiter: text): list<text>

Splits this text around matches of the given delimiter.

Examples:

  • 'the cow jumped over the moon'.split(' ') returns ['the', 'cow', 'jumped', 'over', 'the', 'moon'].

  • 'giggling'.split('g') returns ['', 'i', '', 'lin', ''].

  • 'espresso'.split('a') returns ['espresso'].

Link copied to clipboard
pure function starts_with(prefix: text): boolean

Checks if this text starts with the specified prefix.

Note that for all texts t, t.starts_with('') is true, and for all texts u and v such that u == v, u.starts_with(v) is true.

Link copied to clipboard
(alias) pure function startsWith(prefix: text): boolean

Checks if this text starts with the specified prefix.

Note that for all texts t, t.starts_with('') is true, and for all texts u and v such that u == v, u.starts_with(v) is true.

Link copied to clipboard
pure function sub(start: integer): text

Returns a substring of this text starting from the specified index (inclusive).

pure function sub(start: integer, end: integer): text

Returns a substring of this text from the specified start index (inclusive) to the specified end index (exclusive).

Link copied to clipboard
pure function to_bytes(): byte_array

Converts this text to an array of UTF-8 encoded bytes.

Link copied to clipboard
pure function trim(): text

Returns text matching this one, but with leading and trailing whitespace removed.

Link copied to clipboard
pure function upper_case(): text

Returns the text obtained by converting all alphabetic characters in this text to upper case.

Link copied to clipboard
(alias) pure function upperCase(): text

Returns the text obtained by converting all alphabetic characters in this text to upper case.